<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Controlling Analysis | Elasticsearch: The Definitive Guide [2.x] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch: The Definitive Guide [2.x]">
<link rel="up" href="full-text-search.html" title="Full-Text Search">
<link rel="prev" href="_boosting_query_clauses.html" title="Boosting Query Clauses">
<link rel="next" href="relevance-is-broken.html" title="Relevance Is Broken!">
<meta name="DC.type" content="Learn/Docs/Legacy/Elasticsearch/Definitive Guide/2.x">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="2.x">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<p>
  <strong>WARNING</strong>: The 2.x versions of Elasticsearch have passed their
  <a href="https://www.elastic.co/support/eol">EOL dates</a>. If you are running
  a 2.x version, we strongly advise you to upgrade.
</p>
<p>
  This documentation is no longer maintained and may be removed. For the latest
  information, see the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html">current
  Elasticsearch documentation</a>.
</p>
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch: The Definitive Guide [2.x]</a></span>
»
<span class="breadcrumb-link"><a href="search-in-depth.html">Search in Depth</a></span>
»
<span class="breadcrumb-link"><a href="full-text-search.html">Full-Text Search</a></span>
»
<span class="breadcrumb-node">Controlling Analysis</span>
</div>
<div class="navheader">
<span class="prev">
<a href="_boosting_query_clauses.html">« Boosting Query Clauses</a>
</span>
<span class="next">
<a href="relevance-is-broken.html">Relevance Is Broken! »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="_controlling_analysis"></a>Controlling Analysis<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/100_Full_Text_Search/30_Controlling_analysis.asciidoc">edit</a>
</h2>
</div></div></div>
<p>Queries can find only terms that actually exist in the inverted index, so it
is important to ensure that the same analysis process is applied both to the
document at index time, and to the query string at search time so that the
terms in the query match the terms in the inverted index.</p>
<p>Although we say <em>document</em>, analyzers are determined per field. Each
field can have a different analyzer, either by configuring a specific analyzer
for that field or by falling back on the type, index, or node defaults.  At
index time, a field’s value is analyzed by using the configured or default
analyzer for that field.</p>
<p>For instance, let’s add a new field to <code class="literal">my_index</code>:</p>
<div class="pre_wrapper lang-sense">
<pre class="programlisting prettyprint lang-sense">PUT /my_index/_mapping/my_type
{
    "my_type": {
        "properties": {
            "english_title": {
                "type":     "string",
                "analyzer": "english"
            }
        }
    }
}</pre>
</div>
<div class="sense_widget" data-snippet="snippets/100_Full_Text_Search/30_Analysis.json"></div>
<p>Now we can compare how values in the <code class="literal">english_title</code> field and the <code class="literal">title</code> field are
analyzed at index time by using the <code class="literal">analyze</code> API to analyze the word <code class="literal">Foxes</code>:</p>
<div class="pre_wrapper lang-sense">
<pre class="programlisting prettyprint lang-sense">GET /my_index/_analyze
{
  "field": "title",   <a id="CO65-1"></a><i class="conum" data-value="1"></i>
  "text": "Foxes"
}

GET /my_index/_analyze
{
  "field": "english_title",   <a id="CO65-2"></a><i class="conum" data-value="2"></i>
  "text": "Foxes"
}</pre>
</div>
<div class="sense_widget" data-snippet="snippets/100_Full_Text_Search/30_Analysis.json"></div>
<div class="calloutlist">
<table border="0" summary="Callout list">
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO65-1"><i class="conum" data-value="1"></i></a></p>
</td>
<td align="left" valign="top">
<p>Field <code class="literal">title</code>, which uses the default <code class="literal">standard</code> analyzer, will return the
term <code class="literal">foxes</code>.</p>
</td>
</tr>
<tr>
<td align="left" valign="top" width="5%">
<p><a href="#CO65-2"><i class="conum" data-value="2"></i></a></p>
</td>
<td align="left" valign="top">
<p>Field <code class="literal">english_title</code>, which uses the <code class="literal">english</code> analyzer, will return the term
<code class="literal">fox</code>.</p>
</td>
</tr>
</table>
</div>
<p>This means that, were we to run a low-level <code class="literal">term</code> query for the exact term
<code class="literal">fox</code>, the <code class="literal">english_title</code> field would match but the <code class="literal">title</code> field would
not.</p>
<p>High-level queries like the <code class="literal">match</code> query understand field mappings and can
apply the correct analyzer for each field being queried. We can see this
in action with the <code class="literal">validate-query</code> API:</p>
<div class="pre_wrapper lang-sense">
<pre class="programlisting prettyprint lang-sense">GET /my_index/my_type/_validate/query?explain
{
    "query": {
        "bool": {
            "should": [
                { "match": { "title":         "Foxes"}},
                { "match": { "english_title": "Foxes"}}
            ]
        }
    }
}</pre>
</div>
<div class="sense_widget" data-snippet="snippets/100_Full_Text_Search/30_Analysis.json"></div>
<p>which returns this <code class="literal">explanation</code>:</p>
<pre class="literallayout">(title:foxes english_title:fox)</pre>

<p>The <code class="literal">match</code> query uses the appropriate analyzer for each field to ensure
that it looks for each term in the correct format for that field.</p>
<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_default_analyzers"></a>Default Analyzers<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/100_Full_Text_Search/30_Controlling_analysis.asciidoc">edit</a>
</h3>
</div></div></div>
<p>While we can specify an analyzer at the field level, how do we determine which
analyzer is used for a field if none is specified at the field level?</p>
<p>Analyzers can be specified at three levels: per-field, per-index or the global default.
Elasticsearch works through each level until it finds an analyzer that it can use.
At index time, the order is as follows:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The <code class="literal">analyzer</code> defined in the field mapping, else
</li>
<li class="listitem">
The analyzer named <code class="literal">default</code> in the index settings, which defaults to
</li>
<li class="listitem">
The <code class="literal">standard</code> analyzer
</li>
</ul>
</div>
<p>At search time, the sequence is slightly different:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The <code class="literal">analyzer</code> defined in the query itself, else
</li>
<li class="listitem">
The <code class="literal">analyzer</code> defined in the field mapping, else
</li>
<li class="listitem">
The analyzer named <code class="literal">default</code> in the index settings, which defaults to
</li>
<li class="listitem">
The <code class="literal">standard</code> analyzer
</li>
</ul>
</div>
<p>Occasionally, it makes sense to use a different analyzer at index and search
time. For instance, at index time we may want to index synonyms (for example, for every
occurrence of <code class="literal">quick</code>, we also index <code class="literal">fast</code>, <code class="literal">rapid</code>, and <code class="literal">speedy</code>). But at
search time, we don’t need to search for all of these synonyms.  Instead we
can just look up the single word that the user has entered, be it <code class="literal">quick</code>,
<code class="literal">fast</code>, <code class="literal">rapid</code>, or <code class="literal">speedy</code>.</p>
<p>To enable this distinction, Elasticsearch also supports an
optional <code class="literal">search_analyzer</code> mapping which will only be used at search-time (<code class="literal">analyzer</code>
is still used for indexing). There is also an equivalent <code class="literal">default_search</code> mapping
for configuring the default at the index-level.</p>
<p>Taking these extra parameters into account, the <em>full</em> sequence at search time:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
The <code class="literal">analyzer</code> defined in the query itself, else
</li>
<li class="listitem">
The <code class="literal">search_analyzer</code> defined in the field mapping, else
</li>
<li class="listitem">
The <code class="literal">analyzer</code> defined in the field mapping, else
</li>
<li class="listitem">
The analyzer named <code class="literal">default_search</code> in the index settings, which defaults to
</li>
<li class="listitem">
The analyzer named <code class="literal">default</code> in the index settings, which defaults to
</li>
<li class="listitem">
The <code class="literal">standard</code> analyzer
</li>
</ul>
</div>
</div>

<div class="section">
<div class="titlepage"><div><div>
<h3 class="title">
<a id="_configuring_analyzers_in_practice"></a>Configuring Analyzers in Practice<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/100_Full_Text_Search/30_Controlling_analysis.asciidoc">edit</a>
</h3>
</div></div></div>
<p>The sheer number of places where you can specify an analyzer is quite
overwhelming.  In practice, though, it is pretty simple.</p>
<div class="section">
<div class="titlepage"><div><div>
<h4 class="title">
<a id="_keep_it_simple"></a>Keep it simple<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch-definitive-guide/edit/2.x/100_Full_Text_Search/30_Controlling_analysis.asciidoc">edit</a>
</h4>
</div></div></div>
<p>Most of the time, you will know what fields your documents will contain ahead
of time.  The simplest approach is to set the analyzer for each full-text
field when you create your index or add type mappings.  While this approach is
slightly more verbose, it enables you to easily see which analyzer is being applied
to each field.</p>
<p>Typically, most of your string fields will be exact-value <code class="literal">not_analyzed</code>
fields such as tags or enums, plus a handful of full-text fields that will
use some default analyzer like <code class="literal">standard</code> or <code class="literal">english</code> or some other language.
Then you may have one or two fields that need custom analysis: perhaps the
<code class="literal">title</code> field needs to be indexed in a way that supports <em>find-as-you-type</em>.</p>
<p>You can set the <code class="literal">default</code> analyzer in the index to the analyzer you want to
use for almost all full-text fields, and just configure the specialized
analyzer on the one or two fields that need it.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>A common work flow for time based data like logging is to create a new index
per day on the fly by just indexing into it.  While this work flow prevents
you from creating your index up front, you can still use
<a href="/guide/en/elasticsearch/reference/2.4/indices-templates.html" class="ulink" target="_top">index templates</a>
to specify the settings and mappings that a new index should have.</p>
</div>
</div>
</div>

</div>

</div>
<div class="navfooter">
<span class="prev">
<a href="_boosting_query_clauses.html">« Boosting Query Clauses</a>
</span>
<span class="next">
<a href="relevance-is-broken.html">Relevance Is Broken! »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
